Inside Macintosh: QuickDraw GX Objects /

Chapter 1 - Introduction to QuickDraw GX / Drawing and Hit-Testing Shapes

Hit-Testing

Hit-testing is the process of converting a point in the displayed representation of a shape to a location in the shape object's geometry. For example, when the user clicks the mouse button, hit-testing can tell you what displayed shape, and which part of that shape, the cursor was close to at the moment of clicking. You use hit-testing to select shapes or specific parts of shapes for highlighting or user manipulation, or to position the caret in text and to highlight text ranges. In a sense, hit-testing is the opposite of drawing, because it is a conversion from display representation to internal representation.

When you hit-test a shape, QuickDraw GX generally allows you to determine which part of a shape's geometry corresponds (within a certain tolerance) to the point you are testing against. Tolerance is the distance from a shape or shape part that a hit point can be and still be considered a successful hit. QuickDraw GX provides the following hit-testing functions:

• GXHitTestShape tests a point in local space against a shape's geometry.
• GXHitTestPicture tests a point in local space against a picture shape.
• GXHitTestLayout tests a point in local space against the text of a layout shape.
  Note that you can also use GXHitTestShape to test layout shapes, but the kind of information it returns is different from what GXHitTestLayout returns.
• GXHitTestDevice tests a pixel (a point in device space) against a shape's geometry.

When you use a hit-testing function that returns a shape part, such as GXHitTestShape, the parts of a shape's geometry that you can hit-test for depend on the kind of shape. For example, for a typographic shape, the possible parts could be the bounding box, left side, right side, or side bearing of a glyph. For a line, the possible parts include its bounding rectangle, its geometry, its pen area, and its edges. Figure 1-10 shows the parts of a line involved in a particular hit-test. Shape parts are described in more detail in the chapter "Transform Objects" in this book.

Figure 1-10 Parts of a line for hit-testing

When you set up a hit-test using GXHitTestShape, you specify a tolerance and you also specify which parts of the shape to test against. The GXHitTestShape function returns all specified parts that are within the distance of the hit point defined by the tolerance. For example, if the hit point in Figure 1-10 is less than the tolerance away from the geometry part, the function could determine that the hit point corresponds to the bounds part, the geometry part, the pen part, and the edge part, depending on which of those shape parts you specify in the test.

The GXHitTestShape function analyzes shape parts in a specific order, and returns the distance from the hit point to the first part it encounters that is considered a hit. If you want to know the distance the hit point is from the pen, for example, you need to exclude both the bounds and the geometry parts from the test, because GXHitTestShape tests those first.

The GXHitTestShape function is described in the chapter "Shape Objects" in this
book. The GXHitTestPicture function is described in the picture shapes chapter
of Inside Macintosh: QuickDraw GX Graphics. The GXHitTestLayout function is described in the layout carets, highlighting, and hit-testing chapter of Inside Macintosh: QuickDraw GX Typography. The GXHitTestDevice function is described in the chapter "View-Related Objects" in this book.